Upgrading to Liferay DXP part #2 — working with modules UpgradeSteps

This blog post is a continuation of Liferay DXP upgrade series.

So you are upgrading a former 6.2/dxp database to Liferay DXP, and the process fails on some specific module UpgradeStep?

Sounds familiar to you? So let’s look at what is the path out of the dark…

Photo by Jan Antonin Kolar 🇨🇿 on Unsplash

Stepping out of the dark

First, let’s get some things straight — you want to be in line with the official guidelines.

https://dev.liferay.com/discover/deployment/-/knowledge_base/7-1/pre-upgrade-speed-up-the-process

… and so you are, but your process still experiences problems for some specific module?

The reason has to be that the former 6.2/dxp database that you are upgrading has some inconsistencies, or wrongly transformed data that breaks the upgrade process.

Liferay HELP!

First of all, if you are DXP client, you know Liferay LESA support is always of good help in Upgrade cases, so make sure to make good use of it.

https://help.liferay.com/

But if you are on Community version, you might not get assistance and will have to debug/fix the problematic UpgradeProcess on your own.

Conclusions from debugging

After quick debugging, and lecture of the logs, you will most likely realise that you need to do something right before UpgradeStep, or in between, to make the process working.

The best option here is to fix data directly in a 6.2/dxp environment, before any upgrade procedure. For that, you would usually have to tailor an UpgradeScript for your 6.2/dxp portal that will fix your data using proper API.

The topic of cleanup, in fact, is also mentioned in the guidelines from Liferay. A proper cleanup 6.2/dxp procedure can take significant time to engineer but is the best option that you have — to go through the upgrade process successfully. Stay connected to our https://medium.com/@ableneo blog as we might bring another article to cover that topic alone.

Overriding Lpkg Files for the help

In some cases, you will realise that cleanup procedure is not efficient and you will need to have a possibility to interfere in the middle of the module Upgrade Process.

Here with bits of help comes something formally called by Liferay: ‘Overriding Lpkg Files’.

https://dev.liferay.com/develop/tutorials/-/knowledge_base/7-1/overriding-lpkg-files

Now, this is a technique that should be used with utmost care and respect, since it directly overrides Liferay’s internal modules. however gives you a total control of the process, and a way to have that one-time fixpack procedure during the actual process that ultimately will allow you to implement your fixpack or at least log all the problematic entries in a straightforward way.

Enough, talking, let’s see it in action!

LPKG Override for UpgradeStep in Action

1. Create your module

for the sake of this article, we will create a

blogs-service-ext

2. Copy over a proper build.gradle file from original Liferay module and copy it over to your module directory

in our case:

https://github.com/liferay/com-liferay-blogs/blob/master/blogs-service/build.gradle

(you still may need to comment out some of the lines that are unavailable during build time, such as buildService in this case)

3. Initiate a bnd file for your module

same story as before, take the original bnd file as a basis:

https://github.com/liferay/com-liferay-blogs/blob/master/blogs-service/bnd.bnd

but, as David H Nebinger accurately points out, you will have to solve additional module dependencies

Include-Resource: @com.liferay.blogs.service-x.x.x.jar

Will do the job here, but I recommend a more in-depth lecture of David’s insight in that blog article to fully understand this topic.

4. Copy the selected UpgradeStepRegistrator from original sources

https://github.com/liferay/com-liferay-blogs/blob/master/blogs-service/src/main/java/com/liferay/blogs/internal/upgrade/BlogsServiceUpgrade.java

and register your custom upgrade process, keeping in mind semantic versioning.

5. Add your custom process where you will be able to log/patch your entries directly.

6. build a jar, and put it into [Liferay Home]/osgi/marketplace/override

Now, when you run the Upgrade Tool process again, your module will be taken into consideration.

You can dispose of the overridden jars easily after the upgrade has been completed. To do that, remove them from /override directory when you finish the upgrade-tool process, and your Liferay portal is shut down.

Final word — be cautious!

This technique has a lot of restrictions when it can be used, but it allows you to have direct access to the upgrade steps.

For more details on that topic (especially restrictions), I strongly recommend you to read in full David H Nebinger’s Article in Liferay Community Forum which very well covers the responsibilities and caution that you need to take as a developer, whenever manipulating Liferay’s modules.

Need to upgrade but not sure where to start? Reach out to us in Ableneo. We have rich experience with upgrading important projects to the latest versions of Liferay. Contact us at info@ableneo.com

👏Clap, 👂follow and 🤝join us, ableneo.com

Upgrading to Liferay DXP part #2 — working with modules UpgradeSteps was originally published in ableneo Technology on Medium, where people are continuing the conversation by highlighting and responding to this story.